.TH NITFOL 6
.SH NAME
nitfol \- Z-code interpreter and debugger.
.SH SYNOPSIS
.B nitfol
.I "[options] file"
.SH DESCRIPTION
This manpage was generated from bits of the info page.  See the info page for complete documentation.

Nitfol is a portable interpreter for Z-machine code, the game format used by Infocom and more recently, Inform <http://www.gnelson.demon.co.uk/inform.html>.  Nitfol handles versions one through eight of the format, and attempts to comply with version 1.0 of the Z-machine specification.

You will need game files to use nitfol.  The ``if-archive'' contains a large collection of these, available at <ftp://ftp.gmd.de/if-archive/games/zcode/> or at the USA mirror <http://ifarchive.org/indexes/if-archiveXgamesXzcode.html>.

This manual describes how to use nitfol and how it differs from other Z-machine interpreters.  This manual was written with unix-like systems in mind; ignore that which does not apply to your platform.  Comments on and corrections for this manual and nitfol are appreciated and should be sent to <nitfol@my-deja.com>.

.SH OPTIONS
.TP
.B \-ignore, \-no\-ignore, \-i
Ignore Z-machine strictness errors.  Normally nitfol checks for illegal and undefined Z-machine behaviour and alerts the user.  If you're playing someone else's buggy game, this can be annoying and you should use this option.
.TP
.B \-fullname, \-no\-fullname, \-f
For running under Emacs or DDD.  Tells nitfol to give machine-recognizeable markers when stack frames are displayed instead of displaying the line. Only useful if you are using nitfol as an inferior debugger.
.TP
.B \-command \fIfile\fB, \-x \fIfile
Read commands from this file.  Load a script from a file for playback in the game.
.TP
.B \-pirate, \-no\-pirate, \-P
Aye, matey.  Make the piracy opcode not branch, letting the game know the game disc is not ``genuine.'' Infocom never used this opcode and neither should you, but if obscurity amuses you...
.TP
.B \-quiet, \-no\-quiet, \-q
Do not print introductory messages.  For GDB compatibility.
.TP
.B \-spell, \-no\-spell
Perform spelling correction.  Normally Z-machine games are unforgiving of typos (though they do have an \fBoops\fP command). If you type in a word which isn't in the game's dictionary and have typo correction enabled, nitfol will search for a word which is off by one letter by a substitution, deletion, insertion or transposition.
.TP
.B \-expand, \-no\-expand
Expand one letter abbreviations.  Early Z-machine games don't include `x' as a synonym for `examine' and such.  If the first word in a sentence is one letter long and not recognized by the game, this will attempt to expand it to a full word.
.TP
.B \-symbols \fIfile\fB, \-s \fIfile
Specify symbol file for game.  If you want to perform source-level debugging, you will need to specify a symbol file, which contains the names of variables and tells nitfol how source code corresponds to object code.
.TP
.B \-tandy, \-no\-tandy, \-t
Censors some Infocom games.  Some version 3 games perform minor wording changes when this bit is set to appease the sensitivity of Tandy Corporation.
.TP
.B \-transcript \fIwfile\fB, \-T \fIwfile
Write transcript to this file.  This transcript begins as soon as the game starts.
.TP
.B \-debug, \-no\-debug, \-d
Enter debugger immediatly.  Imitate GDB by not automatically starting the story.
.TP
.B \-prompt \fIstring\fB
Specify debugging prompt.  This is the prompt nitfol prints when it is waiting for a debugging command (as opposed to the > the game story prints when waiting for a game command).  DDD requires this to be `(gdb) '.
.TP
.B \-path \fIstring\fB
Look for games in this directory.  If nitfol cannot find the requested game in the current directory, it looks through the directories listed in the given colon separated string.  The directories specified here are also used to search for gamefiles from saved games.   If this option is not used, nitfol looks at the \fBINFOCOM_PATH\fP environment variable.
.TP
.B \-autoundo, \-no\-autoundo
Ensure \fB@save_undo\fP is called every turn.  If a turn passes with no \fB@save_undo\fP between, this option performs the \fB@save_undo\fP automagically.  Could cause problems with some games which have a different concept of a turn.
.TP
.B \-stacklimit \fInumber\fB, \-S \fInumber
Exit when the stack is this deep.  If a game is infinitely recursing, nitfol will allocate large amounts of memory and take a long time before the problem is reported.  This option makes it fatal to recurse more than the given number of stack frames.  Setting this to 0 makes nitfol allow as many as fit contiguously in memory.  The Z-machine Standards Document recommends games use no more than 1024 words of total stack (frames and pushed data) in ZIP, which roughly works out to 90 routine calls deep.
.TP
.B \-alias \fIstring\fB, \-a \fIstring
Specify an alias.  Adds an alias which will be expanded in read lines before tokenisation.  The alias is of the form \fIname\fP \fIvalue\fP; you will need to use quotes around it on the commandline.
.TP
.B \-ralias \fIstring\fB
Specify an recursive alias.  Adds an alias whose result is checked for further alias expansion.  Identical syntax to adding a normal alias.
.TP
.B \-unalias \fIstring\fB
Remove an alias.  Removes an alias previously added by -alias.  Useful for removing aliases in preference files.
.TP
.B \-random \fInumber\fB, \-r \fInumber
Set random seed.  Normally the random number generator is initialized with the time of day.  If this option is used with a non-zero argument, the given number will be used to initialize the generator and for \fB@random 0\fP.
.TP
.B \-mapsym \fIstring\fB
Specify mapping glyphs.  Nitfol draws maps using ASCII characters; you can choose which characters it uses to draw rooms.  Defaults to `*udb@UDB+', which is, in order: empty room, room with down exit, room with up exit, room with up and down exits, room with player, room with player and up exit, room with player and down exit, room with player and up and down exits, bend symbol.
.TP
.B \-mapsize \fInumber\fB
Specify map size.  Determines the number of lines to be used for the map.
.TP
.B \-maploc \fIstring\fB
Specify map location.  Nitfol creates a Glk window for the map it generates.  The map can be placed `above', `below', to the `right', or the `left', of the main game window.  Follow this option with one those locations.
.TP
.B \-terpnum \fInumber\fB
Specify interpreter number.  Each port of Infocom's Z-machine interpreter was given a number.  `1' for their own DECSystem-20, `2' for Apple IIe, `3' for Macintosh, `4' for Amiga, `5' for Atari ST, `6' for IBM PC, `7' for Commodore 128, `8' for Commodore 64, `9' for Apple IIc, `10' for Apple IIgs, `11' for Tandy Color.  Giving this option makes nitfol claim to be running on the specified system.  A few games change their behaviour slightly depending on which machine type they run.  By default nitfol claims to be on an Apple IIe, as this makes Beyond Zork not do character graphics.
.TP
.B \-terpver \fIstring\fB
Specify interpreter version.  Infocom's interpreters were given versions, typically a capital letter.  Nitfol defaults to `N', Frotz uses `F', and ZIP uses `B'.  Any single character version is allowed.  Multicharacter options are read as a number instead of an ASCII character.  Only known effect upon games is the letter printed by banners and the `version' command.  Version 6 games interpret this as a number instead of a letter.
.SH BUGS

A nitfol bug is any behaviour which makes nitfol reliably misbehave, with the exceptions of bugs in Glk libraries.  These include: anything which makes nitfol crash (other than when nitfol reports `FATAL' errors), anything which causes nitfol to contradict the Z-machine standards documents (except for optional enhancements like spelling correction and debug mode), any buffer overflows, and anything which makes nitfol infinite loop other than infinite loops in the game itself.

Before reporting a bug, make sure the bug is not listed below and your copy of nitfol is not compiled with `-DFAST'.  Please report the version of nitfol, your system type and a series of commands which reliably cause the bug.

Nitfol is lacking:
.IP \(bu
Graphical font (\fIBeyond Zork\fP)  (should use images for this)
.IP \(bu
Terminating character support (mostly \fIBeyond Zork\fP)
.IP \(bu
Reverse video, full color (should querry Glk more aggressively)
.IP \(bu
Unicode support
.IP \(bu
keypad character codes
.IP \(bu
its own random number generator (relies on system one)
.PP

Nitfol does incorrectly:
.IP \(bu
Play is not paused to wait for sounds to complete in \fIThe Lurking Horror\fP.
.IP \(bu
Pictures and text are not placed correctly for v6 games.
.IP \(bu
block quotes are placed in the upper window, so \fBcheapnitfol\fP can't see them.
.IP \(bu
Corrupted save files may make nitfol do bad things.
.IP \(bu
Should figure out a way to handle buggy games like \fIAMFV\fP and \fIVaricella\fP which assume the upper window is 80 columns wide.
.IP \(bu
Doesn't catch header writing other than \fB@storeb\fP and \fB@storew\fP.
.PP

Debugger problems:
.IP \(bu
Sometimes says there's no code at a location where it could be clever and
  find some.
.IP \(bu
\fBofclass\fP, superclass not implemented.
.IP \(bu
Should perform more sanity checks everywhere.
.IP \(bu
Lots of useful commands not yet implemented.
.IP \(bu
\fIobject\fP.\fIfunction\fP is handled incorrectly, both for assignments and calls.
.IP \(bu
Assumes you know what you're doing, so \fBquit\fP, \fBrun\fP, etc., don't prompt you for confirmation.
.PP

Automapping problems:
.IP \(bu
Doesn't work well for random destinations (the forest in \fIAdvent\fP)
.IP \(bu
\fB@get_cursor\fP doesn't return the correct value during automapping since output is disabled.
.IP \(bu
Requires too much work for the end-user; should put in stuff to make it figure out the location global in 95% of games.
.IP \(bu
Doesn't really work if multiple locations are coded as being in the same room (long road in \fIEnchanter\fP).
.IP \(bu
Doesn't show exits which go nowhere, but change the game.
.IP \(bu
Perhaps should use graphics windows when available.
.IP \(bu
Movement causing teleportation confuses it.
.IP \(bu
Reincarnation handling isn't optimal.
.IP \(bu
Still very buggy.
.IP \(bu
It's too slow.
.IP \(bu
Should realize it can add extra bends (especially in one-way passages).
.IP \(bu
Should be able to output nice-looking Postscript.
.IP \(bu
Should store map in saved games (wait until automapping code stabilizes).
.PP

.SH "SEE ALSO"
.RB "`\|" nitfol "\|'"
entry in
.B
info;
.BR frotz (6),
.BR txd (1).
.SH AUTHOR
nitfol was written by Evin Robertson, who can be reached at nitfol@my-deja.com.
